<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta content="en" name="language">
	<title>Magick::Exception</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link media="screen" href="../docutils-articles.css" type="text/css" rel="stylesheet">

</head>

<body>

<div class="banner">
<img src="../images/gm-107x76.png" alt="GraphicMagick logo" width="107" height="76" />
<span class="title">GraphicsMagick</span>
<form action="http://www.google.com/search">
  <input type="hidden" name="domains" value="www.graphicsmagick.org" />
  <input type="hidden" name="sitesearch" value="www.graphicsmagick.org" />
<span class="nowrap"><input type="text" name="q" size="25" maxlength="255" />&nbsp;<input type="submit" name="sa" value="Search" /></span>
</form>
</div>


<div class="navmenu">
<ul>
  <li><a href="../index.html">Home</a></li>
  <li><a href="../project.html">Project</a></li>
  <li><a href="../download.html">Download</a></li>
  <li><a href="../README.html">Install</a></li>
  <li><a href="../Hg.html">Source</a></li>
  <li><a href="../NEWS.html">News</a> </li>
  <li><a href="../utilities.html">Utilities</a></li>
  <li><a href="../programming.html">Programming</a></li>
  <li><a href="../reference.html">Reference</a></li>
</ul>
</div>

<main id="magick-exception">
<h1 class="title">Magick::Exception</h1>
<!-- -*- mode: rst -*- -->
<!-- This text is in reStucturedText format, so it may look a bit odd. -->
<!-- See http://docutils.sourceforge.net/rst.html for details. -->
<p><em>Exception</em> represents the base class of objects thrown when
Magick++ reports an error. Magick++ throws C++ exceptions synchronous
with the operation where the error occurred. This allows errors to be
trapped within the enclosing code (perhaps the code to process a
single image) while allowing the code to be written with a simple
coding style.</p>
<p>A try/catch block should be placed around any sequence of operations
which can be considered an important body of work. For example, if
your program processes lists of images and some of these images may be
defective, by placing the try/catch block around the entire sequence
of code that processes one image (including instantiating the image
object), you can minimize the overhead of error checking while
ensuring that all objects created to deal with that object are safely
destroyed (C++ exceptions unroll the stack until the enclosing try
block, destroying any objects on the stack).</p>
<p>Note that any objects allocated via 'new' with a pointer on the stack
are not automatically destroyed by unrolling the stack via a C++
exception so that it may be necessary to catch the exception at each
level, destroy any objects allocated via 'new' (or malloc()) and then
re-throw the exception.  This includes constructors which might
encounter an exception while the object is being constructed and
should destroy any already-allocated data.  Magick++ classes are
designed to be <strong>very</strong> tiny so it is recommended to automatically
allocate them on the stack when possible rather than via 'new'.</p>
<p>The pseudo code for the main loop of your program may look like:</p>
<pre class="literal-block"> using namespace std;
 for infile in list
 {
   try {
     // Construct an image instance first so that we don't have to worry
     // about object construction failure due to a minor warning exception
     // being thrown.
     Magick::Image image;

     // Determine if Warning exceptions are thrown.
     // Use is optional.  Set to true to block Warning exceptions.
     image.quiet( false );

     try {
       // Try reading image file
       image.read(infile);
     }
     catch( Magick::WarningCoder &amp;warning )
     {
       // Process coder warning while loading file (e.g. TIFF warning)
       // Maybe the user will be interested in these warnings (or not).
       // If a warning is produced while loading an image, the image
       // can normally still be used (but not if the warning was about
       // something important!)
       cerr &lt;&lt; “Coder Warning: “ &lt;&lt; warning.what() &lt;&lt; endl;
     }
     catch( Magick::Warning &amp;warning )
     {
       // Handle any other Magick++ warning.
       cerr &lt;&lt; “Warning: “ &lt;&lt; warning.what() &lt;&lt; endl;
     }
     catch( Magick::ErrorFileOpen &amp;error )
     {
       // Process Magick++ file open error
       cerr &lt;&lt; “Error: “ &lt;&lt; error.what() &lt;&lt; endl;
       continue; // Try next image.
     }
     try {
       image.rotate(90);
       image.write(“outfile”);
     }
     catch ( MagickExeption &amp; error)
     {
        // Handle problem while rotating or writing outfile.
        cerr &lt;&lt; “Caught Magick++ exception: “ &lt;&lt; error.what() &lt;&lt; endl;
     }
   }
   catch( std::exception &amp;error )
   {
      // Process any other exceptions derived from standard C++ exception
      cerr &lt;&lt; “Caught C++ STD exception: “ &lt;&lt; error.what() &lt;&lt; endl;
   }
   catch( ... )
   {
     // Process *any* exception (last-ditch effort). There is not a lot
     // you can do here other to retry the operation that failed, or exit
     // the program.
   }
 }

The desired location and number of try/catch blocks in your program
depends how sophisticated its error handling must be. Very simple
programs may use just one try/catch block.</pre>
<p>The <em>Exception</em> class is derived from the C++ standard
<em>std::exception</em> class. This means that it contains a C++ string
containing additional information about the error (e.g to display to
the user). Obtain access to this string via the what() method.  For
example:</p>
<pre class="literal-block">catch( Exception &amp;error_ )
{
  cout &lt;&lt; &quot;Caught exception: &quot; &lt;&lt; error_.what() &lt;&lt; endl;
}</pre>
<p>The classes <em>Warning</em> and <em>Error</em> derive from the <em>Exception</em>
class. Exceptions derived from <em>Warning</em> are thrown to represent
non-fatal errors which may effect the completeness or quality of the
result (e.g. one image provided as an argument to montage is
defective). In most cases, a <em>Warning</em> exception may be ignored by
catching it immediately, processing it (e.g. printing a diagnostic)
and continuing on. Exceptions derived from <em>Error</em> are thrown to
represent fatal errors that can not produce a valid result
(e.g. attempting to read a file which does not exist).</p>
<p>The specific derived exception classes are shown in the following tables:</p>
<table>
<caption>Warning (Suspect but completed) Sub-Classes</caption>
<colgroup>
<col style="width: 35%" />
<col style="width: 65%" />
</colgroup>
<thead>
<tr><th class="head"><p>Warning</p></th>
<th class="head"><p>Warning Description</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>WarningUndefined</p></td>
<td><p>Unspecified type.</p></td>
</tr>
<tr><td><p>WarningBlob</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCache</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCoder</p></td>
<td><p>Issued by some coders.</p></td>
</tr>
<tr><td><p>WarningConfigure</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCorruptImage</p></td>
<td><p>Issued when an image may be corrupt.</p></td>
</tr>
<tr><td><p>WarningDelegate</p></td>
<td><p>Reported by a subordinate program.</p></td>
</tr>
<tr><td><p>WarningDraw</p></td>
<td><p>Reported by the rendering subsystem.</p></td>
</tr>
<tr><td><p>WarningFileOpen</p></td>
<td><p>Reported when file could not be opened.</p></td>
</tr>
<tr><td><p>WarningImage</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningMissingDelegate</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningModule</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningMonitor</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningOption</p></td>
<td><p>Reported when an option is incorrect.</p></td>
</tr>
<tr><td><p>WarningRegistry</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningResourceLimit</p></td>
<td><p>Reported when a resource is exhausted.</p></td>
</tr>
<tr><td><p>WarningStream</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningType</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningXServer</p></td>
<td><p>Warnings reported by the X11 subsystem.</p></td>
</tr>
</tbody>
</table>
<table>
<caption>Error (Failed) Sub-Classes</caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 67%" />
</colgroup>
<thead>
<tr><th class="head"><p>Error</p></th>
<th class="head"><p>Error Description</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>ErrorUndefined</p></td>
<td><p>Unspecified error type.</p></td>
</tr>
<tr><td><p>ErrorBlob</p></td>
<td><p>Reported by BLOB I/O subsystem.</p></td>
</tr>
<tr><td><p>ErrorCache</p></td>
<td><p>Reported by the pixel cache subsystem.</p></td>
</tr>
<tr><td><p>ErrorCoder</p></td>
<td><p>Reported by coders (image format support).</p></td>
</tr>
<tr><td><p>ErrorConfigure</p></td>
<td><p>Reported while loading configuration files.</p></td>
</tr>
<tr><td><p>ErrorCorruptImage</p></td>
<td><p>Reported when the image file is corrupt.</p></td>
</tr>
<tr><td><p>ErrorDelegate</p></td>
<td><p>Reported by a subordinate program</p></td>
</tr>
<tr><td><p>ErrorDraw</p></td>
<td><p>Reported while drawing on image.</p></td>
</tr>
<tr><td><p>ErrorFileOpen</p></td>
<td><p>Reported when the image file can not be opened.</p></td>
</tr>
<tr><td><p>ErrorImage</p></td>
<td><p>Reported while drawing.</p></td>
</tr>
<tr><td><p>ErrorMissingDelegate</p></td>
<td><p>Reported when optional add-on library or
subordinate program is missing (but is needed).</p></td>
</tr>
<tr><td><p>ErrorModule</p></td>
<td><p>Reported by the module loader subsystem.</p></td>
</tr>
<tr><td><p>ErrorMonitor</p></td>
<td><p>Reported by the progress monitor.</p></td>
</tr>
<tr><td><p>ErrorOption</p></td>
<td><p>Reported when option is malformed or out of range.</p></td>
</tr>
<tr><td><p>ErrorRegistry</p></td>
<td><p>Reported by the image/BLOB registry subsystem.</p></td>
</tr>
<tr><td><p>ErrorResourceLimit</p></td>
<td><p>Reported when a program resource is exhausted.</p></td>
</tr>
<tr><td><p>ErrorStream</p></td>
<td><p>Reported by the pixel stream subsystem.</p></td>
</tr>
<tr><td><p>ErrorType</p></td>
<td><p>Reported by the type (font) rendering subsystem.</p></td>
</tr>
<tr><td><p>ErrorXServer</p></td>
<td><p>Reported by the X11 subsystem.</p></td>
</tr>
</tbody>
</table>
<p>Note that <em>ErrorMissingDelegate</em> is a &quot;catch-all&quot; error reported when
GraphicsMagick is unable to figure out how to open the file.</p>
<p>Copyright © Bob Friesenhahn 1999 - 2022</p>
</main>


<hr class="docutils">
<div class="document">
    <p><a href="../Copyright.html">Copyright</a> © GraphicsMagick Group 2002-2025<!--SPONSOR_LOGO--></p>
</div>

</main>
</body>
</html>
